

<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Scudo Hardened Allocator &#8212; LLVM 9 documentation</title>
    <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/language_data.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Using -opt-bisect-limit to debug optimization errors" href="OptBisect.html" />
    <link rel="prev" title="Fuzzing LLVM libraries and tools" href="FuzzingLLVM.html" />
<style type="text/css">
  table.right { float: right; margin-left: 20px; }
  table.right td { border: 1px solid #ccc; }
</style>

  </head><body>
<div class="logo">
  <a href="index.html">
    <img src="_static/logo.png"
         alt="LLVM Logo" width="250" height="88"/></a>
</div>

    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="OptBisect.html" title="Using -opt-bisect-limit to debug optimization errors"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="FuzzingLLVM.html" title="Fuzzing LLVM libraries and tools"
             accesskey="P">previous</a> |</li>
  <li><a href="http://llvm.org/">LLVM Home</a>&nbsp;|&nbsp;</li>
  <li><a href="index.html">Documentation</a>&raquo;</li>

        <li class="nav-item nav-item-this"><a href="">Scudo Hardened Allocator</a></li> 
      </ul>
    </div>


    <div class="document">
      <div class="documentwrapper">
          <div class="body" role="main">
            
  <div class="section" id="scudo-hardened-allocator">
<h1>Scudo Hardened Allocator<a class="headerlink" href="#scudo-hardened-allocator" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#introduction" id="id1">Introduction</a></p></li>
<li><p><a class="reference internal" href="#design" id="id2">Design</a></p></li>
<li><p><a class="reference internal" href="#usage" id="id3">Usage</a></p></li>
<li><p><a class="reference internal" href="#error-types" id="id4">Error Types</a></p></li>
</ul>
</div>
<div class="section" id="introduction">
<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>The Scudo Hardened Allocator is a user-mode allocator based on LLVM Sanitizer’s
CombinedAllocator, which aims at providing additional mitigations against heap
based vulnerabilities, while maintaining good performance.</p>
<p>Currently, the allocator supports (was tested on) the following architectures:</p>
<ul class="simple">
<li><p>i386 (&amp; i686) (32-bit);</p></li>
<li><p>x86_64 (64-bit);</p></li>
<li><p>armhf (32-bit);</p></li>
<li><p>AArch64 (64-bit);</p></li>
<li><p>MIPS (32-bit &amp; 64-bit).</p></li>
</ul>
<p>The name “Scudo” has been retained from the initial implementation (Escudo
meaning Shield in Spanish and Portuguese).</p>
</div>
<div class="section" id="design">
<h2><a class="toc-backref" href="#id2">Design</a><a class="headerlink" href="#design" title="Permalink to this headline">¶</a></h2>
<div class="section" id="allocator">
<h3>Allocator<a class="headerlink" href="#allocator" title="Permalink to this headline">¶</a></h3>
<p>Scudo can be considered a Frontend to the Sanitizers’ common allocator (later
referenced as the Backend). It is split between a Primary allocator, fast and
efficient, that services smaller allocation sizes, and a Secondary allocator
that services larger allocation sizes and is backed by the operating system
memory mapping primitives.</p>
<p>Scudo was designed with security in mind, but aims at striking a good balance
between security and performance. It is highly tunable and configurable.</p>
</div>
<div class="section" id="chunk-header">
<h3>Chunk Header<a class="headerlink" href="#chunk-header" title="Permalink to this headline">¶</a></h3>
<p>Every chunk of heap memory will be preceded by a chunk header. This has two
purposes, the first one being to store various information about the chunk,
the second one being to detect potential heap overflows. In order to achieve
this, the header will be checksummed, involving the pointer to the chunk itself
and a global secret. Any corruption of the header will be detected when said
header is accessed, and the process terminated.</p>
<p>The following information is stored in the header:</p>
<ul class="simple">
<li><p>the 16-bit checksum;</p></li>
<li><p>the class ID for that chunk, which is the “bucket” where the chunk resides
for Primary backed allocations, or 0 for Secondary backed allocations;</p></li>
<li><p>the size (Primary) or unused bytes amount (Secondary) for that chunk, which is
necessary for computing the size of the chunk;</p></li>
<li><p>the state of the chunk (available, allocated or quarantined);</p></li>
<li><p>the allocation type (malloc, new, new[] or memalign), to detect potential
mismatches in the allocation APIs used;</p></li>
<li><p>the offset of the chunk, which is the distance in bytes from the beginning of
the returned chunk to the beginning of the Backend allocation;</p></li>
</ul>
<p>This header fits within 8 bytes, on all platforms supported.</p>
<p>The checksum is computed as a CRC32 (made faster with hardware support)
of the global secret, the chunk pointer itself, and the 8 bytes of header with
the checksum field zeroed out. It is not intended to be cryptographically
strong.</p>
<p>The header is atomically loaded and stored to prevent races. This is important
as two consecutive chunks could belong to different threads. We also want to
avoid any type of double fetches of information located in the header, and use
local copies of the header for this purpose.</p>
</div>
<div class="section" id="delayed-freelist">
<h3>Delayed Freelist<a class="headerlink" href="#delayed-freelist" title="Permalink to this headline">¶</a></h3>
<p>A delayed freelist allows us to not return a chunk directly to the Backend, but
to keep it aside for a while. Once a criterion is met, the delayed freelist is
emptied, and the quarantined chunks are returned to the Backend. This helps
mitigate use-after-free vulnerabilities by reducing the determinism of the
allocation and deallocation patterns.</p>
<p>This feature is using the Sanitizer’s Quarantine as its base, and the amount of
memory that it can hold is configurable by the user (see the Options section
below).</p>
</div>
<div class="section" id="randomness">
<h3>Randomness<a class="headerlink" href="#randomness" title="Permalink to this headline">¶</a></h3>
<p>It is important for the allocator to not make use of fixed addresses. We use
the dynamic base option for the SizeClassAllocator, allowing us to benefit
from the randomness of the system memory mapping functions.</p>
</div>
</div>
<div class="section" id="usage">
<h2><a class="toc-backref" href="#id3">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<div class="section" id="library">
<h3>Library<a class="headerlink" href="#library" title="Permalink to this headline">¶</a></h3>
<p>The allocator static library can be built from the LLVM build tree thanks to
the <code class="docutils literal notranslate"><span class="pre">scudo</span></code> CMake rule. The associated tests can be exercised thanks to the
<code class="docutils literal notranslate"><span class="pre">check-scudo</span></code> CMake rule.</p>
<p>Linking the static library to your project can require the use of the
<code class="docutils literal notranslate"><span class="pre">whole-archive</span></code> linker flag (or equivalent), depending on your linker.
Additional flags might also be necessary.</p>
<p>Your linked binary should now make use of the Scudo allocation and deallocation
functions.</p>
<p>You may also build Scudo like this:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">cd $LLVM/projects/compiler-rt/lib</span>
<span class="go">clang++ -fPIC -std=c++11 -msse4.2 -O2 -I. scudo/*.cpp \</span>
<span class="gp">  $</span><span class="o">(</span><span class="se">\l</span>s sanitizer_common/*.<span class="o">{</span>cc,S<span class="o">}</span> <span class="p">|</span> grep -v <span class="s2">&quot;sanitizer_termination\|sanitizer_common_nolibc\|sancov_\|sanitizer_unwind\|sanitizer_symbol&quot;</span><span class="o">)</span> <span class="se">\</span>
  -shared -o libscudo.so -pthread
</pre></div>
</div>
<p>and then use it with existing binaries as follows:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">LD_PRELOAD=`pwd`/libscudo.so ./a.out</span>
</pre></div>
</div>
</div>
<div class="section" id="clang">
<h3>Clang<a class="headerlink" href="#clang" title="Permalink to this headline">¶</a></h3>
<p>With a recent version of Clang (post rL317337), the allocator can be linked with
a binary at compilation using the <code class="docutils literal notranslate"><span class="pre">-fsanitize=scudo</span></code> command-line argument, if
the target platform is supported. Currently, the only other Sanitizer Scudo is
compatible with is UBSan (eg: <code class="docutils literal notranslate"><span class="pre">-fsanitize=scudo,undefined</span></code>). Compiling with
Scudo will also enforce PIE for the output binary.</p>
</div>
<div class="section" id="options">
<h3>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
<p>Several aspects of the allocator can be configured on a per process basis
through the following ways:</p>
<ul class="simple">
<li><p>at compile time, by defining <code class="docutils literal notranslate"><span class="pre">SCUDO_DEFAULT_OPTIONS</span></code> to the options string
you want set by default;</p></li>
<li><p>by defining a <code class="docutils literal notranslate"><span class="pre">__scudo_default_options</span></code> function in one’s program that
returns the options string to be parsed. Said function must have the following
prototype: <code class="docutils literal notranslate"><span class="pre">extern</span> <span class="pre">&quot;C&quot;</span> <span class="pre">const</span> <span class="pre">char*</span> <span class="pre">__scudo_default_options(void)</span></code>, with a
default visibility. This will override the compile time define;</p></li>
<li><p>through the environment variable SCUDO_OPTIONS, containing the options string
to be parsed. Options defined this way will override any definition made
through <code class="docutils literal notranslate"><span class="pre">__scudo_default_options</span></code>.</p></li>
</ul>
<p>The options string follows a syntax similar to ASan, where distinct options
can be assigned in the same string, separated by colons.</p>
<p>For example, using the environment variable:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">SCUDO_OPTIONS=&quot;DeleteSizeMismatch=1:QuarantineSizeKb=64&quot; ./a.out</span>
</pre></div>
</div>
<p>Or using the function:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="s">&quot;C&quot;</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">__scudo_default_options</span><span class="p">()</span> <span class="p">{</span>
  <span class="k">return</span> <span class="s">&quot;DeleteSizeMismatch=1:QuarantineSizeKb=64&quot;</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The following options are available:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 27%" />
<col style="width: 15%" />
<col style="width: 15%" />
<col style="width: 44%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p>Option</p></td>
<td><p>64-bit default</p></td>
<td><p>32-bit default</p></td>
<td><p>Description</p></td>
</tr>
<tr class="row-even"><td><p>QuarantineSizeKb</p></td>
<td><p>256</p></td>
<td><p>64</p></td>
<td><p>The size (in Kb) of quarantine used to delay
the actual deallocation of chunks. Lower value
may reduce memory usage but decrease the
effectiveness of the mitigation; a negative
value will fallback to the defaults. Setting
<em>both</em> this and ThreadLocalQuarantineSizeKb to
zero will disable the quarantine entirely.</p></td>
</tr>
<tr class="row-odd"><td><p>QuarantineChunksUpToSize</p></td>
<td><p>2048</p></td>
<td><p>512</p></td>
<td><p>Size (in bytes) up to which chunks can be
quarantined.</p></td>
</tr>
<tr class="row-even"><td><p>ThreadLocalQuarantineSizeKb</p></td>
<td><p>1024</p></td>
<td><p>256</p></td>
<td><p>The size (in Kb) of per-thread cache use to
offload the global quarantine. Lower value may
reduce memory usage but might increase
contention on the global quarantine. Setting
<em>both</em> this and QuarantineSizeKb to zero will
disable the quarantine entirely.</p></td>
</tr>
<tr class="row-odd"><td><p>DeallocationTypeMismatch</p></td>
<td><p>true</p></td>
<td><p>true</p></td>
<td><p>Whether or not we report errors on
malloc/delete, new/free, new/delete[], etc.</p></td>
</tr>
<tr class="row-even"><td><p>DeleteSizeMismatch</p></td>
<td><p>true</p></td>
<td><p>true</p></td>
<td><p>Whether or not we report errors on mismatch
between sizes of new and delete.</p></td>
</tr>
<tr class="row-odd"><td><p>ZeroContents</p></td>
<td><p>false</p></td>
<td><p>false</p></td>
<td><p>Whether or not we zero chunk contents on
allocation and deallocation.</p></td>
</tr>
</tbody>
</table>
<p>Allocator related common Sanitizer options can also be passed through Scudo
options, such as <code class="docutils literal notranslate"><span class="pre">allocator_may_return_null</span></code> or <code class="docutils literal notranslate"><span class="pre">abort_on_error</span></code>. A detailed
list including those can be found here:
<a class="reference external" href="https://github.com/google/sanitizers/wiki/SanitizerCommonFlags">https://github.com/google/sanitizers/wiki/SanitizerCommonFlags</a>.</p>
</div>
</div>
<div class="section" id="error-types">
<h2><a class="toc-backref" href="#id4">Error Types</a><a class="headerlink" href="#error-types" title="Permalink to this headline">¶</a></h2>
<p>The allocator will output an error message, and potentially terminate the
process, when an unexpected behavior is detected. The output usually starts with
<code class="docutils literal notranslate"><span class="pre">&quot;Scudo</span> <span class="pre">ERROR:&quot;</span></code> followed by a short summary of the problem that occurred as
well as the pointer(s) involved. Once again, Scudo is meant to be a mitigation,
and might not be the most useful of tools to help you root-cause the issue,
please consider <a class="reference external" href="https://github.com/google/sanitizers/wiki/AddressSanitizer">ASan</a>
for this purpose.</p>
<p>Here is a list of the current error messages and their potential cause:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">&quot;corrupted</span> <span class="pre">chunk</span> <span class="pre">header&quot;</span></code>: the checksum verification of the chunk header
has failed. This is likely due to one of two things: the header was
overwritten (partially or totally), or the pointer passed to the function is
not a chunk at all;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&quot;race</span> <span class="pre">on</span> <span class="pre">chunk</span> <span class="pre">header&quot;</span></code>: two different threads are attempting to manipulate
the same header at the same time. This is usually symptomatic of a
race-condition or general lack of locking when performing operations on that
chunk;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&quot;invalid</span> <span class="pre">chunk</span> <span class="pre">state&quot;</span></code>: the chunk is not in the expected state for a given
operation, eg: it is not allocated when trying to free it, or it’s not
quarantined when trying to recycle it, etc. A double-free is the typical
reason this error would occur;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&quot;misaligned</span> <span class="pre">pointer&quot;</span></code>: we strongly enforce basic alignment requirements, 8
bytes on 32-bit platforms, 16 bytes on 64-bit platforms. If a pointer passed
to our functions does not fit those, something is definitely wrong.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&quot;allocation</span> <span class="pre">type</span> <span class="pre">mismatch&quot;</span></code>: when the optional deallocation type mismatch
check is enabled, a deallocation function called on a chunk has to match the
type of function that was called to allocate it. Security implications of such
a mismatch are not necessarily obvious but situational at best;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&quot;invalid</span> <span class="pre">sized</span> <span class="pre">delete&quot;</span></code>: when the C++14 sized delete operator is used, and
the optional check enabled, this indicates that the size passed when
deallocating a chunk is not congruent with the one requested when allocating
it. This is likely to be a <a class="reference external" href="https://software.intel.com/en-us/forums/intel-c-compiler/topic/783942">compiler issue</a>,
as was the case with Intel C++ Compiler, or some type confusion on the object
being deallocated;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&quot;RSS</span> <span class="pre">limit</span> <span class="pre">exhausted&quot;</span></code>: the maximum RSS optionally specified has been
exceeded;</p></li>
</ul>
<p>Several other error messages relate to parameter checking on the libc allocation
APIs and are fairly straightforward to understand.</p>
</div>
</div>


            <div class="clearer"></div>
          </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="OptBisect.html" title="Using -opt-bisect-limit to debug optimization errors"
             >next</a> |</li>
        <li class="right" >
          <a href="FuzzingLLVM.html" title="Fuzzing LLVM libraries and tools"
             >previous</a> |</li>
  <li><a href="http://llvm.org/">LLVM Home</a>&nbsp;|&nbsp;</li>
  <li><a href="index.html">Documentation</a>&raquo;</li>

        <li class="nav-item nav-item-this"><a href="">Scudo Hardened Allocator</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2003-2020, LLVM Project.
      Last updated on 2020-09-20.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
    </div>
  </body>
</html>